home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Diamond Collection / The Diamond Collection (Software Vault)(Digital Impact).ISO / cdr13 / wsm14.zip / WORDSMRT.DOC < prev    next >
Text File  |  1995-01-16  |  34KB  |  1,024 lines

  1. WORDSMRT.DOC
  2. Documentation for WordSmart (WSM.EXE), a file-reformatting utility
  3. Version: 1.4
  4. January 16, 1995
  5.  
  6.  WORDSMART and its documentation are Copyright 1992, 1994 by:
  7.  
  8.  Lambert Klein
  9.  P.O. Box 611
  10.  Wayne MI  48184-0611
  11.  Voice telephone: (313) 467-8070        Fax:    313-467-8373
  12.  
  13.  GEnie:       L.Klein1
  14.  CompuServe:  72010,624
  15.  Internet:    72010.624@compuserve.com
  16.  AOL:         LKlein3990
  17.  
  18.  
  19.  
  20.  
  21.       ┌──────────────────────┐
  22.       │  TABLE OF CONTENTS:  │
  23.       └──────────────────────┘
  24.  
  25.      WordSmart is Shareware  ......  page 3
  26.  
  27.      Thanks  ......................  page 3
  28.  
  29.      Purpose of WordSmart  ........  page 4
  30.  
  31.      Features of WordSmart  .......  page 4
  32.  
  33.      Running WordSmart  ...........  page 5
  34.  
  35.      Basic program syntax  ........  page 5
  36.  
  37.      Program options  .............  page 7
  38.  
  39.      Options summary  .............  page 8
  40.  
  41.      Options in detail  ...........  page 8
  42.  
  43.              Left margin  .........  page 8
  44.  
  45.              Right margin  ........  page 9
  46.  
  47.              Removing all EOLs
  48.              within paragraphs  ...  page 11
  49.  
  50.              Preventing reformatting page 12
  51.  
  52.              What happens during
  53.              -R processing  .......  page 13
  54.  
  55.              Write output file  ...  page 14
  56.  
  57.              Over-write existing
  58.              file  ................  page 15
  59.  
  60.              Remove form-feeds  ...  page 16
  61.  
  62.              Remove multiple spaces  page 16
  63.  
  64.              Print registration ...  page 16
  65.  
  66.        Remove blank lines (reg)  ..  page 17
  67.  
  68.        Quiet processing (reg)  ....  page 17
  69.  
  70.      Piping and redirection  ......  page 18
  71.  
  72.      Errorlevels  .................  page 20
  73.  
  74.      Example bat file  ............  page 20
  75.  
  76.      Registration benefits  .......  page 21
  77.  
  78.  
  79.                                                          page 3
  80.  
  81.  
  82. WordSmart is shareware. If you try it out, find it useful, and
  83. go on using it - please register it. Registration is only
  84. $14.00. plus $4.00 shipping and handling.
  85.  
  86. I hope you find WordSmart useful. If you have any comments,
  87. suggestions, bug reports, and so on, please send them to me
  88. at the address shown above. See the file PROGRAMS.TXT, also
  89. in the archive WORDSMRT.ZIP, for information on my other
  90. shareware, including PrintPlus, my menu-driven dot-matrix
  91. printer control program.
  92.  
  93. -- Lambert Klein
  94.  
  95. ============================================================
  96.  
  97.  
  98. Any registered or trademarked product names mentioned in
  99. this documentation are the property of their respective
  100. owners or publishers.
  101.  
  102. ============================================================
  103.  
  104.  
  105.  
  106.  
  107.  ╓┬───────────┬╖
  108.  ║│  THANKS:  │║
  109.  ╙┴───────────┴╜
  110.  
  111. I would like to thank Mike Arst for his continuous testing
  112. and debugging of WordSmart. There have been many hours of testing
  113. and coding put into WordSmart.
  114.  
  115. Thanks goes to the Writer of WordSmart's documentation, who
  116. also happens to be Mike Arst!
  117.  
  118.  
  119.  
  120.                                                          page 4
  121.  ╓┬────────────┐
  122.  ║│  PURPOSE   │
  123.  ╙┴────────────┘
  124.  
  125. WordSmart, written entirely in assembly language, is a fast
  126. reformatter for text files.
  127.  
  128. For instance, WordSmart can increase the line length of text
  129. files created with relatively short lines, perhaps (as with this
  130. file) because the writer assumed you'd be using a typical dot-
  131. matrix printer setup. But if you are using compressed mode for
  132. printing, you might prefer wider lines. WordSmart helps with this
  133. by automatically increasing line lengths for you (or decreasing
  134. them - your choice); you won't have to do so manually in a text
  135. editor or word processor.
  136.  
  137. FEATURES IN BOTH REGISTERED AND UNREGISTERED
  138. VERSIONS OF WORDSMART
  139.  
  140. o   Accepts input in the form of a source file whose name you
  141.     specify on the command line, or accepts input from "standard
  142.     input" (i.e., via a "pipe").
  143.  
  144. o   Writes an output file whose name you specify on the command
  145.     line; otherwise, writes to "standard output," allowing you
  146.     to redirect the results of processing to a file name or
  147.     else "pipe" the output to some other program.
  148.  
  149. o   Can over-write an existing file at your option
  150.  
  151. o   Adds to or removes spaces at the left sides of lines.
  152.  
  153. o   Changes the lengths of lines (from 10 characters wide
  154.     up to 60,000 characters wide). Can be used to remove "hard"
  155.     line breaks within paragraphs completely, preserving the
  156.     paragraph-endings themselves.
  157.  
  158. o   Removes form-feed characters.
  159.  
  160. o   Reduces runs of multiple spaces to a single space.
  161.  
  162. o   Returns errorlevels, useful when WordSmart is run from
  163.     batch files.
  164.  
  165. o   Removes blank lines from files.
  166.  
  167. ADDITIONAL FEATURES AVAILABLE ONLY IN THE
  168. REGISTERED VERSION
  169.  
  170.  
  171. o   "Quiet" mode - no screen display during processing
  172.  
  173.  
  174. The program will usually be referred to hereafter in the
  175. documentation simply as "WSM."
  176.  
  177.  
  178.                                                          page 5
  179.  ╓┬─────────────────┐
  180.  ║│ RUNNING WSM.EXE │
  181.  ╙┴─────────────────┘
  182.  
  183. WSM can read past an EOF character (Control-Z) and will treat it
  184. as if it were an ordinary character. WSM also treats a NULL (with
  185. a decimal value of 0) no differently from any other character.
  186.  
  187. Limitations:
  188.  
  189. Line-ending characters: WSM cannot process files with Unix-style
  190. line endings (line feeds only), nor those with Mac-style line
  191. endings (carriage returns only). The files must have standard DOS
  192. line endings (carriage return plus line feed).
  193.  
  194. Types of input files: WSM is intended for use only with plain-
  195. text files, not files saved in the "document" format of programs
  196. like WordStar, Microsoft Word, or WordPerfect. Using WSM to alter
  197. such files will probably make them unreadable by the word
  198. processing programs that created them.
  199.  
  200.  ╓┬──────────────────────┐
  201.  ║│ BASIC PROGRAM SYNTAX │
  202.  ╙┴──────────────────────┘
  203.  
  204. Typing WSM alone at the DOS prompt brings up a help-screen
  205. containing a summary of the command-line options and information
  206. about the exit codes (errorlevels) WSM returns.
  207.  
  208. Typical command line:
  209.  
  210. WSM input [options] > output
  211.  
  212. Where:
  213.  
  214. input       is the name of the file you want to process;
  215.  
  216. [options]   are one or more of the command-line options
  217.             (switches) discussed below; and
  218.  
  219. > output    is an optional command whereby you use DOS
  220.             redirection to create an output file.
  221.  
  222. NOTE:       THE NAME OF THE FILE TO BE USED FOR INPUT MUST BE
  223.             THE FIRST PARAMETER ON THE COMMAND LINE.
  224.  
  225.             If you do not put the input file name first,
  226.             WordSmart will display an error message ("source
  227.             path error"), and it will halt without doing any
  228.             further work.
  229.  
  230.             The input file name CANNOT contain the DOS
  231.             wildcards "*" or "?".
  232.  
  233.  
  234.                                                          page 6
  235.  
  236. Other ways to write the command line:
  237.  
  238.         WSM input [options] | another_program
  239.  
  240. In this kind of command, you use a "pipe" to send WSM's output
  241. not to a file, but to some other program ("another_program" in
  242. the above example) that can read from "standard input."
  243.  
  244. This also works:
  245.  
  246.         another_program | WSM [options] > output
  247.  
  248.  
  249. In this case, you pipe some other program's output to WSM. Note
  250. that in this case, you do NOT give WSM the name of an input file.
  251. You could use WSM's "write output file" option (see below) or use
  252. "> output."
  253.  
  254. NOTE:  There are some risks to be aware of when using redirection
  255.        to write output files. They will be discussed in greater
  256.        detail in the section called "Piping and output
  257.        redirection."
  258.  
  259. A WSM command line that does not contain a "write output to
  260. file..." command forces the results of processing to be sent only
  261. to "standard output" - to the screen. You can use this to preview
  262. the results of processing and without first having to write an
  263. output file. If you use a program like LIST.COM (a shareware file
  264. viewer by Vernon Buerg), you can pipe output from WSM.EXE to LIST,
  265. thus:
  266.  
  267.         WSM input [switches] | list /s
  268.  
  269. (LIST's "/s" option is required when it is receiving input via
  270. "pipe" like that.)
  271.  
  272.  
  273.                                                          page 7
  274.  
  275.  ╓┬─────────────────┐
  276.  ║│ PROGRAM OPTIONS │
  277.  ╙┴─────────────────┘
  278.  
  279. WordSmart's functions are all invoked with command-line "switches."
  280.  
  281. Each "switch" is a hyphen, followed by a single letter (with no
  282. space between the hyphen and the letter). The case of the letter
  283. is unimportant. Both of the following are "legal" forms of the
  284. "-B" switch:
  285.  
  286.         -b      -B
  287.  
  288. Some switches require additional information, which will be
  289. referred to hereafter as an "argument." For example, -W tells
  290. WSM to write an output file; the output file name argument
  291. follows the -W.
  292.  
  293. You can either add or omit a space between a switch and its
  294. argument. Both of the following are legal ways to add the output
  295. file name argument to the "-w" switch:
  296.  
  297.          -Woutput      -W output
  298.  
  299. There are two possible switch characters: the hyphen and the
  300. forward slash. Either -W or /W would work for the switch used
  301. to specify the output file name. All of the following are "legal"
  302. ways of writing that switch (the file name argument is
  303. represented by the word "output"):
  304.  
  305.         -woutput      -w output      /woutput      /w output
  306.  
  307.         -Woutput      -W output      /Woutput      /W output
  308.  
  309.  
  310.  
  311.                                                          page 8
  312.  ╓┬──────────────────────╖
  313.  ║│ OPTIONS - SUMMARIZED ║
  314.  ╙┴──────────────────────╜
  315.  
  316. Switch   Purpose
  317.  
  318. -L       Specify the left margin; must be followed by a number
  319.          indicating the number of spaces to add at the left
  320.          margin.
  321.  
  322. -R       Specify the right margin; must be followed by a number
  323.          indicating the maximum line width.
  324.  
  325. -W       Write output file; must be followed by the name of the
  326.          file to write.
  327.  
  328. -O       Over-write an existing file without query. This option
  329.          takes no arguments.
  330.  
  331. -F       Remove form-feed characters. This option takes no
  332.          arguments.
  333.  
  334. -S       Remove runs of multiple spaces, reducing the string
  335.          of spaces to one space only. This option takes no
  336.          arguments.
  337.  
  338. -I       Send a WordSmart registration form directly to the
  339.          printer. This option takes no arguments.
  340.  
  341. -B       Removes all blank lines past one. -B0 removes all.
  342.  
  343. -Q       "Quiet" mode - no screen display at all during or
  344.          after processing. This option takes no arguments.
  345.          AVAILABLE ONLY IN THE REGISTERED VERSION.
  346.  
  347.  
  348.  ╓┬───────────────────────────────┐
  349.  ║│ OPTIONS - DESCRIBED IN DETAIL │
  350.  ╙┴───────────────────────────────┘
  351.  
  352.  
  353.  ┌────────────────────────────────┐
  354.  │ -L   ADD SPACES TO LEFT MARGIN │
  355.  └────────────────────────────────┘
  356.  
  357. "-L" is always followed by a two- or three-digit number
  358. indicating the number of spaces to add at the left of each line
  359. of the input file. Example:
  360.  
  361. -L5  would add 5 spaces to the beginning of each line. If the file
  362. has no left-margin indents at all, the command -L5 would put the
  363. first NON-space character on each line in column 6.
  364.  
  365.  
  366.                                                          page 9
  367.  
  368. If there are already spaces at the start of a line, the -L
  369. command adds the additional spaces to them. For example, a file
  370. whose lines are already indented by two spaces would be
  371. indented by seven spaces after you'd used -L5.
  372.  
  373. In the present version of WSM, the -L command does not REMOVE
  374. spaces from the left margin. Thus, -L0 has no meaning. (Removal
  375. of spaces from the left margin is being considered for a future
  376. version of WordSmart.)
  377.  
  378. Example - if this is a line in the input file:
  379.  
  380. Here is a test line
  381.  
  382. ... it looks this way after processing via -L5:
  383.  
  384.      Here is a test line
  385.  
  386. The first non-space character ("H") is now at column 6.
  387.  
  388. CAUTION:  Numbers higher than 200, used with the -L switch,
  389.           might cause corruption in or truncation of the output
  390.           file.
  391.  
  392.  ┌───────────────────────┐
  393.  │ -R   NEW RIGHT MARGIN │
  394.  └───────────────────────┘
  395. -R is followed by a number 2 to 5 digits long, indicating a new
  396. line width (the number cannot exceed 60000). The number does not
  397. necessarily mean how many characters long the line will be; it is
  398. an "absolute" setting, indicating the right-most COLUMN NUMBER
  399. past which a line must break to a new line. (There's more
  400. information later in this documentation concerning exactly how
  401. WSM makes line-ending decisions).
  402.  
  403. For instance, if the input file has no left-margin indents at
  404. all, and if you use the -R switch with an argument of 50, the
  405. widest possible output line will be 50 characters long. On the
  406. other hand, if you were to use these commands:
  407.  
  408.          -L10  -R50
  409.  
  410. ... then WSM would add 10 spaces to the left margin and re-
  411. format lines out to column 50 (maximum). In that case, there
  412. would be a maximum of 40 characters on each line, NOT including
  413. the spaces added at the beginning of the line.
  414.  
  415.  
  416.                                                          page 10
  417. Example - lines that break at column 25:
  418.  
  419. This is an example of
  420. lines that don't extend
  421. past column 25. The goal
  422. is to re-break them with
  423. the command -R45 so that
  424. they break at column 45.
  425.  
  426. After processing with the command -R45:
  427.  
  428. This is an example of lines that don't extend
  429. past column 25. The goal is to re-break them
  430. with the command -R45 so that they break at
  431. column 45.
  432.  
  433.  
  434. A nonsensical command like  -L40 -R30  would, if taken literally,
  435. add 40 spaces to the start of each line but then try to break all
  436. lines at column 30. If you give WSM an instruction like that, it
  437. ignores the left-margin command entirely and takes only the right-
  438. margin command into account.
  439.  
  440. If you use an argument less than 10, -R defaults to a value of
  441. 10. (There is one notable exception; -R0. See "Removing All Line
  442. Breaks Within Paragraphs," below.)
  443.  
  444. If you have a text file in which each paragraph is a single long
  445. line, use -R plus a two-digit argument (80 or below) if you want to
  446. make the file more easily readable on-screen. But note: If there
  447. are NO blank lines in such a file, and if none of the lines is
  448. indented, processing it with WSM.EXE will cause the entire file to
  449. be treated as a single paragraph, and you'll lose all paragraph
  450. breaks. The solution would be to add blank lines between paragraphs
  451. and then process the file with WSM.
  452.  
  453. Where processing begins and ends:
  454.  
  455. For WordSmart's purposes, a paragraph is one or more lines with
  456. at least one blank line above and below it (them). If a line
  457. appears blank but contains spaces, WSM still treats it as a blank
  458. line. The reason is that, before processing begins, WSM removes any
  459. spaces at the right side of a line - "trailing spaces" - if they
  460. are the last characters before the line boundary. (Thus, a line
  461. containing only spaces has all of its spaces removed before
  462. processing begins.)
  463.  
  464.  
  465.                                                          page 11
  466.  ┌────────────────────────────────────────────┐
  467.  │ REMOVING ALL LINE BREAKS WITHIN PARAGRAPHS │
  468.  └────────────────────────────────────────────┘
  469.  
  470. Omitting the -R switch entirely from the WordSmart command line,
  471. OR using the command -R0 (zero), tells WSM to remove ALL line
  472. endings within paragraphs in the input file. Using -R0 (or no
  473. -R command at all) is a quick way to turn each paragraph of the
  474. input file into a single long line (see below for exceptions,
  475. however).
  476.  
  477. This is useful if you will import the text file into a desktop
  478. publishing (DTP) program. You almost always want a DTP program to
  479. make its own line-ending decisions, but its ability to do so is
  480. always defeated by "hard" line breaks within paragraphs. In the
  481. ideal situation, each paragraph is a single long line, and the
  482. only "hard" line breaks in the file are those at the very ends of
  483. the paragraphs.
  484.  
  485. -R0 (or no -R at all) will preserve the FINAL line boundary of
  486. each paragraph, AS LONG AS THERE IS AT LEAST ONE BLANK LINE ABOVE
  487. AND BELOW EACH PARAGRAPH.
  488.  
  489. Example: Suppose the input file looks like this:
  490.  
  491. Line one.
  492. Line two.
  493. Line three.
  494. Line four.
  495.  
  496. Line five.
  497. Line six.
  498.  
  499. Result of processing the file with -R0 (or no -R command
  500. at all):
  501.  
  502. Line one. Line two. Line three. Line four.
  503.  
  504. Line five. Line six.
  505.  
  506.  
  507.                                                          page 12
  508.  ┌─────────────────────────┐
  509.  │ PREVENTING REFORMATTING │
  510.  └─────────────────────────┘
  511.  
  512. If, while re-breaking lines in a file, WSM encounters a line
  513. that is already indented from the left margin - using either
  514. spaces or Tab characters - it will not move any part of that
  515. line up to the previous line.
  516.  
  517. This is a handy way to prevent reformatting of certain lines.
  518. Suppose the input file looks like this:
  519.  
  520. Line one.
  521. Line two.
  522.   Line three.
  523.   Line four.
  524. Line five.
  525.   Line six.
  526. Line seven.
  527.  
  528. Line eight.
  529.   Line nine.
  530.  
  531.  
  532. Result of processing the file with -R0 (or no -R command):
  533.  
  534. Line one. Line two.
  535.   Line three.
  536.   Line four. Line five.
  537.   Line six. Line seven.
  538.  
  539. Line eight.
  540.   Line nine.
  541.  
  542. When WSM changes the line length, no part of an already-indented
  543. line will be merged with the one ABOVE it. However, it might be
  544. merged with any NON-INDENTED line BELOW it (whether the latter
  545. occurs depends on the argument to the -R switch - if you have
  546. used -R at all).
  547.  
  548. Try a few experiments to get a feel for how line-width
  549. reformatting (and exceptions thereto) works.
  550.  
  551.  
  552.                                                          page 13
  553.  ┌─────────────────────────────────────┐
  554.  │ WHAT HAPPENS DURING "-R" PROCESSING │
  555.  └─────────────────────────────────────┘
  556.  
  557. First, the program strips trailing spaces from all lines.
  558.  
  559. Then WSM breaks lines at a space or a hyphen. It NEVER breaks up
  560. a word unless the word already contains a hyphen. Space
  561. permitting on a given line, it leaves the part of the word to the
  562. left of the hyphen, and the hyphen itself, on the line and brings
  563. the part of the word to the right of the hyphen down to the next
  564. line. This line:
  565.  
  566. I won't look the same, post-processing, eh?
  567.  
  568. ... might look like this after WSM finishes with it:
  569.  
  570. I won't look the same, post-
  571. processing, eh?
  572.  
  573. If there isn't room on the upper line for that part of the word
  574. (plus the hyphen itself), WSM brings the ENTIRE word down to the
  575. next line, thus:
  576.  
  577. I won't look the same,
  578. post-processing, eh?
  579.  
  580. Dashes:
  581.  
  582. Hyphens sometimes appear in text files to indicate "long" dashes.
  583. WSM treats such character strings - like that -- (or that)
  584. differently from how it deals with hyphens in other situations.
  585.  
  586. Suppose the input file contains a paragraph like this:
  587.  
  588. Here are some lines --       Or:     Here are some lines -
  589. not many -- with dashes.             not many - with dashes.
  590.  
  591. If you use WSM to increase the file's right margin, the above two
  592. lines might become:
  593.  
  594. Here are a few lines -- not many -- containing dashes.
  595.  
  596.         Or:
  597.  
  598. Here are a few lines - not many - containing dashes.
  599.  
  600. WSM makes this kind of change whether or not there is a space (or
  601. more than one space) between the "dash" and the end of the line.
  602. The key here is that the "dash" must be PRECEDED by a space,
  603. which tells WSM that the hyphen is used as a "dash" and not to
  604. break a word. 
  605.  
  606.  
  607.                                                          page 14
  608.  
  609. If "dashes"--(like these)--are NOT preceded by spaces, the results
  610. might not be just right in the output file. You might need to do
  611. a bit of editing afterward, removing a space WSM will sometimes
  612. add to the right of such "dashes" in the output file (if the
  613. double hyphen falls at the very end of a line in the input file).
  614.  
  615.  
  616.  ┌────────────────────────┐
  617.  │ -W   WRITE OUTPUT FILE │
  618.  └────────────────────────┘
  619.  
  620. The -W switch tells WordSmart to write an output file and
  621. requires a file name argument. Omitting the argument causes an
  622. error message to appear, and no processing occurs - except when
  623. you've "piped" some other program's output to WSM for use as its
  624. own input. (There's more information about that in the section
  625. below called "Piping and Output Redirection.")
  626.  
  627. WSM will NEVER allow you to use the same file name for input and
  628. output when you use the -W switch. (But if you use redirection,
  629. all bets are off - see the piping/redirection information below
  630. for more about this.)
  631.  
  632. The output file name can contain path information but CANNOT
  633. contain the DOS wildcards "*" or "?".
  634.  
  635. If you specify a subdirectory that does not exist, WSM halts with
  636. an error message. (If you make that error when using the
  637. REGISTERED version and if you have used the -Q switch for "quiet"
  638. processing, WSM just beeps.)
  639.  
  640. Example - to process an input file called INPUT.DOC and write
  641. an output file called OUTPUT.DOC:
  642.  
  643.          WSM input.doc -r50 -w output.doc
  644.  
  645. Over-writing an existing output file or choosing a new name:
  646.  
  647. If you are not using the -O switch, and if you specify an output
  648. file that now exists, WSM will beep, open a window on the screen
  649. announcing that the file exists, and ask you to make one of three
  650. choices: Select a new file name, over-write the existing file, or
  651. quit.
  652.  
  653. Press "Q" or ESC to quit at once - no further action.
  654.  
  655. Press "O" to over-write the existing file (unless it is write-
  656. protected).
  657.  
  658.  
  659.                                                          page 15
  660.  
  661. Press "N" to open a window in which you type a new file name.
  662. This also opens a window first containing the message "INSERT
  663. OFF." Pressing ENTER or ESC right away cancels the new-file-name
  664. prompt and tells WSM to quit without doing anything. Or type the
  665. new output file name (including path information, if need be) at
  666. the prompt, then press ENTER to continue processing. WSM then
  667. writes the output file.
  668.  
  669. (If you decide to over-write the existing file after all, re-type
  670. its name at the new-file-name prompt. WSM presents the "over-
  671. write/new file name/quit" prompt again. Type "O" to over-write
  672. the file.)
  673.  
  674. The new-output-name prompt supports a few simple editing
  675. keystrokes: The left- and right-arrow keys move the cursor back
  676. and forth across characters in the prompt line without erasing
  677. any characters. BACKSPACE erases the character to the left of the
  678. cursor. DEL erases the character underneath the cursor.
  679.  
  680. Pressing INS toggles insert-mode on and off (and toggles the text
  681. in the smaller window from "INSERT OFF" to "INSERT ON" and back).
  682. With insert-mode ON, typing characters into the prompt line
  683. pushes any existing characters to the right; with insert-mode
  684. OFF, typing characters into the prompt over-strikes any
  685. characters now there.
  686.  
  687. You can, initially, type file names much longer than the legal
  688. DOS limit. But if you do so, after you press ENTER, WSM
  689. will beep and inform you that you've typed an illegal file
  690. name. Press ENTER after reading this error message, and you'll
  691. be returned to the new-file-name prompt.
  692.  
  693. The -W switch is one way to write an output file; using
  694. redirection is another. That method will be discussed shortly.
  695.  
  696.  
  697.  ┌───────────────────────────────┐
  698.  │ -O   OVER-WRITE EXISTING FILE │
  699.  └───────────────────────────────┘
  700.  
  701. Use the -O switch (no arguments) to suppress WSM's query about
  702. over-writing an existing output file. Example:
  703.  
  704. WSM input.doc -R50 -w output.doc -o
  705.  
  706. The -O switch can appear anywhere to the right of the input file
  707. name, and you can use the switch (without causing an error
  708. message) whether or not the output file name already exists.
  709.  
  710.  
  711.  
  712.                                                          page 16
  713.  ┌──────────────────────────────────┐
  714.  │ -F   REMOVE FORM-FEED CHARACTERS │
  715.  └──────────────────────────────────┘
  716.  
  717. Use -F (no arguments) to remove printer form-feed (FF) characters
  718. (Control-L, decimal value, 12).
  719.  
  720. If the FF character is by itself on a line, -F deletes the ENTIRE
  721. line (including line boundary). If the FF character appears at
  722. the start or end of a line containing other text, WSM will remove
  723. the FF itself but will not remove any other text on the line
  724. (aside from trailing spaces).
  725.  
  726.  ┌─────────────────────────────┐
  727.  │ -S   REMOVE MULTIPLE SPACES │
  728.  └─────────────────────────────┘
  729.  
  730. Use -S (no arguments) to reduce strings of two or more spaces in
  731. a row to a single space.
  732.  
  733. This is handy for removing, say, multiple spaces following
  734. punctuation. (Multiple spacing is not desirable if you're sending
  735. the text to a typesetting or DTP system.)
  736.  
  737. -S is also handy for unjustifying text whose writer has used
  738. multiple spaces to left/right-justify the lines. -S always leaves
  739. a SINGLE space in place of the string of multiple spaces
  740. (including at the beginnings of lines that have been indented by
  741. two or more spaces; this version of WSM is not able to remove ALL
  742. spaces at the start of lines).
  743.  
  744.  ┌──────────────────────────────────────┐
  745.  │ -I   PRINT REGISTRATION FORM/INVOICE │
  746.  └──────────────────────────────────────┘
  747.  
  748. The -I switch takes no arguments. Give the command:
  749.  
  750.         WSM -I
  751.  
  752. to print a WordSmart registration form on your printer. Make sure
  753. the printer is on and ready before giving the command. WordSmart
  754. does not do a "printer-ready?" check before starting the print
  755. routine.
  756.  
  757. -I works in both the registered and unregistered versions but is
  758. not noted in the registered version's help-screen.
  759.  
  760.  
  761.                                                          page 17
  762.  
  763.  ╓╥────────────────────────────╖
  764.  ║║ -B   REMOVE BLANK LINES -  ║
  765.  ╙╨────────────────────────────╜
  766.  
  767. Use -B (no arguments) to remove all blank lines in the file past
  768. one, including lines that begin with spaces.
  769. -B0 removes all blank lines.
  770.  
  771. NOTE:  This command will NOT remove lines that begin with one or
  772.        more tab characters but that are otherwise blank (i.e.,
  773.        they contain nothing other than tabs or spaces). But lines
  774.        that begin with one or more spaces WILL be removed even if
  775.        there are tabs after the spaces.
  776.  
  777.  
  778.  ╓╥─────────────────────────────────────────────────────╖
  779.  ║║ -Q   "QUIET" PROCESSING - *REGISTERED VERSION ONLY* ║
  780.  ╙╨─────────────────────────────────────────────────────╜
  781.  
  782. Use -Q (no arguments) to suppress all WordSmart screen displays.
  783. If there is any error during processing, you are alerted to the
  784. problem only via a beep. -Q is useful if you run WSM from batch
  785. files and want full control over the screen displays during
  786. execution of the batch files.
  787.  
  788. In some situations, WSM will not beep if there is an error when
  789. you're using the -Q switch. But you can check for errors by
  790. testing for the exit code (errorlevel) WSM returns (errorlevels
  791. are discussed shortly).
  792.  
  793.  
  794.                                                          page 18
  795.  ╓┬───────────────────────────────┐
  796.  ║│ PIPING AND OUTPUT REDIRECTION │
  797.  ╙┴───────────────────────────────┘
  798.  
  799. WordSmart can take as input either a file whose name you
  800. specify on the command line, or the output of some other
  801. process - via "piping."
  802.  
  803. Suppose you use an automated search/replace program called SR that
  804. can write to standard output or can read from standard input.
  805. Examples:
  806.  
  807.         SR command | WSM [options]
  808.  
  809. Or:
  810.  
  811.  
  812.         WSM [options] | SR command
  813.  
  814. In the first case, you pipe the SR's output to WSM. In the
  815. second, you pipe WSM's output to SR.
  816.  
  817. When you tell WSM to get its information from standard input, do
  818. NOT put the name of an input file into the WSM command line.
  819.  
  820. Given a command like the following:
  821.  
  822.         another_program | WSM input.doc [options]
  823.  
  824. ... WSM completely ignores the piped information and reads
  825. only INPUT.DOC, instead.
  826.  
  827. Writing output files using redirection:
  828.  
  829. You can use WSM's -W switch to write an output file, or you can
  830. use DOS redirection (">" and ">>").
  831.  
  832. Using ">" can be risky. Suppose you'd like to process the file
  833. INPUT.DOC and over-write it with the changed version - same file
  834. name - rather than write a new file. So you give this command:
  835.  
  836. WSM input.doc [options] > input.doc
  837.  
  838. Result: A file called INPUT.DOC that is only ZERO BYTES LONG.
  839. Definitely not what you wanted.
  840.  
  841. Reason: DOS (not WSM) creates the zero-byte file. Then WSM reads
  842. the input file. But by that time, there isn't anything to read
  843. other than a zero-byte file! If you have only one copy of
  844. INPUT.DOC, you'll have lost it for good.
  845.  
  846.  
  847.                                                          page 19
  848.  
  849. Don't EVER try to over-write your existing file that way. Play
  850. it safe; process the file as follows:
  851.  
  852.         WSM input.doc [options] > output.doc
  853.  
  854. I.e., use a different output file name (or forget redirection
  855. and use WordSmart's -W switch).
  856. The following sort of command is also risky:
  857.  
  858.         WSM [options] < input.doc > input.doc
  859.  
  860. It might work well at some times, but destroy or corrupt your
  861. input file at other times. The following is much safer:
  862.  
  863.         WSM [options] < input.doc > output.doc
  864.  
  865. The following doesn't work, either:
  866.  
  867.         WSM input.doc [options] -w output.doc > new.doc
  868.  
  869. You think, perhaps, that you can create two identical output files
  870. at the same time - OUTPUT.DOC and NEW.DOC? Doesn't work. In that
  871. case, WSM writes OUTPUT.DOC and DOS itself writes a zero-byte file
  872. called NEW.DOC.
  873.  
  874. Redirection and screen displays:
  875.  
  876. When you use redirection, you don't give WSM.EXE enough
  877. information to create complete screen displays. If you pipe
  878. information to WSM, it doesn't display a proper input file name -
  879. because there isn't an input file to begin with.
  880.  
  881. If you write an output file via redirection, the WSM screen
  882. display doesn't show any output file name.
  883.  
  884.  
  885.                                                          page 20
  886.  ╓┬─────────────┐
  887.  ║│ ERRORLEVELS │
  888.  ╙┴─────────────┘
  889. WordSmart returns 7 different exit codes (errorlevels):
  890.  
  891. Code    Meaning
  892.  
  893. 0      Processing was successful
  894.  
  895. 1     "Read" error - couldn't find the specified input file.
  896.  
  897. 2      Can't write the output file because you gave it the same
  898.        name as the input file.
  899.  
  900.       (NOTE: Using output redirection completely defeats
  901.       WordSmart's ability to check for that kind of error.)
  902.  
  903. 3      Can't over-write the specified output file - it now
  904.        exists (and you haven't used the -O switch).
  905.  
  906. 4      Can't write the specified output file - you've given
  907.        a drive and/or path name that doesn't exist. WSM also
  908.        returns this errorlevel if you try to write an output
  909.        file to a floppy drive that isn't ready, or to a write-
  910.        protected disk.
  911.  
  912. 5      Can't over-write the existing file because it's write-
  913.        protected.
  914.  
  915. 255    Returned if you type WSM without any command-line
  916.        options at all.
  917.  
  918.  
  919. The errorlevels become most useful when you're running WSM from a
  920. batch file and are using the -Q ("quiet") switch, in which case
  921. there are no screen displays at all.
  922.  
  923. See the file WORDSMRT.BAT for a simple example of checking for the
  924. return of errorlevels in a batch file. The batch file uses WSM's
  925. -Q switch, which will not function if you don't yet have the
  926. registered version of WSM; but you will still be able to see how
  927. the errorlevel-checking works. (The presence of -Q in the command
  928. line will not cause the unregistered version to return any error
  929. messages.)
  930.  
  931.  ╓┬───────────────────┐
  932.  ║│ ABOUT EXAMPLE.BAT │
  933.  ╙┴───────────────────┘
  934. EXAMPLE.BAT, included in the WordSmart distribution archive, is a
  935. simple batch file that shows the results of processing using
  936. various -R commands.
  937.  
  938. EXAMPLE.BAT uses the file you're reading right now (WORDSMRT.DOC)
  939. for input, and it writes an output file called XXXXXXX_._XX. Once
  940. you're done using EXAMPLE.BAT, be sure to delete XXXXXXX_._XX.
  941.  
  942.  
  943.                                                          page 21
  944.  
  945. Type EXAMPLE at the DOS prompt for information on the batch
  946. file's syntax.
  947.  
  948. I hope you find WordSmart useful. I will greatly appreciate your
  949. registering it.
  950.  
  951. -- Lambert Klein
  952.  
  953.  
  954.  ┌┬───────────────────────────────────────────────────┬┐
  955.  ││ Documentation by Mike Arst, CompuServe 70403,1337 ││
  956.  └┴───────────────────────────────────────────────────┴┘
  957.  
  958.  
  959.  ┌┬────────────────────────┬┐
  960.  ││ REGISTRATION BENEFITS: ││
  961.  └┴────────────────────────┴┘
  962.  
  963. You have a 30-day evaluation period to try out WordSmart.
  964. After 30 days you must register WordSmart to legally continue
  965. its use.
  966.  
  967. When you register WordSmart you receive the following:
  968.  
  969. 1. A disk with the Registered version of WordSmart,
  970.    branded with your name and serial number.
  971.  
  972. 2. Other Shareware and Freeware.
  973.  
  974. 3. A printed manual for WordSmart.
  975.  
  976. 4. Voice, mail and Email support.
  977.  
  978. 5. Any extra features that are added to WordSmart. This
  979.    will include the the -Q switch for quiet screen during 
  980.    processing.
  981.  
  982. 6. The great feeling of registering a high-caliber program
  983.    at a very reasonable price!
  984.  
  985. To print the registration form type     WSM -I [Enter]
  986. at the Dos prompt.
  987.  
  988. Thank you for your support!
  989.  
  990.  Lambert Klein
  991.  PO Box 611
  992.  Wayne MI  48184-0611
  993.  
  994. You can register WordSmart on CompuServe also. Just "GO SWREG".
  995.  
  996. Program Title:          WordSmart 
  997. Registration ID:        562
  998.  
  999.  
  1000.      CREDIT CARD ORDERS ONLY -
  1001.  
  1002.      You can order with MC, Visa, Amex, or Discover from Public (software)
  1003.      Library by calling 800-2424-PsL or 713-524-6394 or by FAX to 713-524-
  1004.      6398 or by CIS Email to 71355,470. You can also mail credit card
  1005.      orders to PsL at P.O.Box 35705, Houston, TX 77235-5705.
  1006.  
  1007.      THE ABOVE NUMBERS ARE FOR ORDERS ONLY.
  1008.  
  1009.      Any questions about the status of the shipment of the order, refunds,
  1010.      registration options, product details, technical support, volume
  1011.      discounts, dealer pricing, site licenses, etc, must be directed to
  1012.      Lambert Klein, Voice: 313-467-8070, Fax: 313-467-8373, Email or mail.
  1013.  
  1014.      To insure that you get the latest version, PsL will notify us the day
  1015.      of your order and we will ship the product directly to you. 
  1016.  
  1017. Non- Credit card orders should be sent to the Author: Lambert Klein.
  1018.  
  1019.  
  1020.  
  1021. AmiPro(r) and ClickBook(tm) were used to produce WordSmart's printed manual.
  1022.  
  1023.  
  1024.